Expand description
§libSQL API for Rust
libSQL is an embeddable SQL database engine based on SQLite. This Rust API is a batteries-included wrapper around the SQLite C API to support transparent replication while retaining compatibility with the SQLite ecosystem, such as the SQL dialect and extensions. If you are building an application in Rust, this is the crate you should use. There are also libSQL language bindings of this Rust crate to other languages such as JavaScript, Python, Go, and C.
§Getting Started
To get started, you first need to create a Database
object and then open a Connection
to it, which you use to query:
use libsql::Builder;
let db = Builder::new_local(":memory:").build().await.unwrap();
let conn = db.connect().unwrap();
conn.execute("CREATE TABLE IF NOT EXISTS users (email TEXT)", ()).await.unwrap();
conn.execute("INSERT INTO users (email) VALUES ('alice@example.org')", ()).await.unwrap();
§Embedded Replicas
Embedded replica is libSQL database that’s running in your application process, which keeps a local copy of a remote database. They are useful if you want to move data in the memory space of your application for fast access.
You can open an embedded read-only replica by using the Database::open_with_local_sync
constructor:
use libsql::Builder;
use libsql::replication::Frames;
let mut db = Builder::new_local_replica("/tmp/test.db").build().await.unwrap();
let frames = Frames::Vec(vec![]);
db.sync_frames(frames).await.unwrap();
let conn = db.connect().unwrap();
conn.execute("SELECT * FROM users", ()).await.unwrap();
§Remote database
It is also possible to create a libsql connection that does not open a local datatbase but instead sends queries to a remote database.
use libsql::Builder;
let db = Builder::new_remote("libsql://my-remote-db.com", "my-auth-token").build().await.unwrap();
let conn = db.connect().unwrap();
conn.execute("CREATE TABLE IF NOT EXISTS users (email TEXT)", ()).await.unwrap();
conn.execute("INSERT INTO users (email) VALUES ('alice@example.org')", ()).await.unwrap();
§WASM
Due to WASM requiring !Send
support and the Database
type supporting async and using
async_trait
to abstract between the different database types, we are unable to support WASM
via the Database
type. Instead, we have provided simpler parallel types in the wasm
module that provide access to our remote HTTP protocol in WASM.
§Examples
You can find more examples in the examples
directory.
§Feature flags
This crate provides a few feature flags that will help you improve compile times by allowing you to reduce the dependencies needed to compile specific features of this crate. For example, you may not want to compile the libsql C code if you just want to make HTTP requests. Feature flags may be used by including the libsql crate like:
libsql = { version = "*", default-features = false, features = ["core", "replication", "remote" ]
By default, all the features are enabled but by providing default-features = false
it will
remove those defaults.
The features are descirbed like so:
core
this includes the core C code that backs both the basic local database usage and embedded replica features.replication
this feature flag includes thecore
feature flag and adds on top HTTP code that will allow you to sync you remote database locally.remote
this feature flag only includes HTTP code that will allow you to run queries against a remote database.
Re-exports§
pub use errors::Error;
pub use params::params_from_iter;
Modules§
- Deserialization utilities.
- ffi
core
C ffi for libsql. - This module contains all
Param
related utilities and traits. - replication
replication
Utilities used when using a replicated version of libsql.
Macros§
- Construct named params from a hetergeneous set of params types.
- Construct positional params from a hetergeneous set of params types.
Structs§
- Represents a libsql column.
- A connection to some libsql database, this can be a remote one or a local one.
- A struct that knows how to build
Connection
’s, this type does not do much work until theDatabase::connect
fn is called. - EncryptionConfig
core
- OpenFlags
core
Flags that can be passed to libsql to open a database in specific modes. - A libsql row.
- A set of rows returned from a connection.
- RowsFuture
core
- A cached prepared statement.
- A transaction on some connection.
Enums§
- Cipher
core
- Transaction types that correlate to sqlite3 transactions and additional ones introduced by libsql.
- A borrowed version of
Value
. - The possible types a column can be in libsql.
Functions§
- version
core
Return the version of the underlying SQLite library as a string. - version_number
core
Return the version of the underlying SQLite library as a number.
Type Aliases§
- Convenient alias for
Result
using thelibsql::Error
type.